home *** CD-ROM | disk | FTP | other *** search
/ PC World 2006 July & August / PCWorld_2006-07-08_cd.bin / komunikace / apache / apache_2[1].2.2-win32-x86-no_ssl.msi / Data1.cab / _742E7DA7B2567AE56D2BB22ACD35B77F < prev    next >
Text File  |  2005-02-04  |  14KB  |  358 lines
  1. /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as
  2.  * applicable.
  3.  *
  4.  * Licensed under the Apache License, Version 2.0 (the "License");
  5.  * you may not use this file except in compliance with the License.
  6.  * You may obtain a copy of the License at
  7.  *
  8.  *     http://www.apache.org/licenses/LICENSE-2.0
  9.  *
  10.  * Unless required by applicable law or agreed to in writing, software
  11.  * distributed under the License is distributed on an "AS IS" BASIS,
  12.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13.  * See the License for the specific language governing permissions and
  14.  * limitations under the License.
  15.  */
  16.  
  17. /* Portions of this file are covered by */
  18. /* -*- mode: c; c-file-style: "k&r" -*-
  19.  
  20.   strnatcmp.c -- Perform 'natural order' comparisons of strings in C.
  21.   Copyright (C) 2000 by Martin Pool <mbp@humbug.org.au>
  22.  
  23.   This software is provided 'as-is', without any express or implied
  24.   warranty.  In no event will the authors be held liable for any damages
  25.   arising from the use of this software.
  26.  
  27.   Permission is granted to anyone to use this software for any purpose,
  28.   including commercial applications, and to alter it and redistribute it
  29.   freely, subject to the following restrictions:
  30.  
  31.   1. The origin of this software must not be misrepresented; you must not
  32.      claim that you wrote the original software. If you use this software
  33.      in a product, an acknowledgment in the product documentation would be
  34.      appreciated but is not required.
  35.   2. Altered source versions must be plainly marked as such, and must not be
  36.      misrepresented as being the original software.
  37.   3. This notice may not be removed or altered from any source distribution.
  38. */
  39.  
  40. #ifndef APR_STRINGS_H
  41. #define APR_STRINGS_H
  42.  
  43. /**
  44.  * @file apr_strings.h
  45.  * @brief APR Strings library
  46.  */
  47.  
  48. #include "apr.h"
  49. #include "apr_errno.h"
  50. #include "apr_pools.h"
  51. #define APR_WANT_IOVEC
  52. #include "apr_want.h"
  53.  
  54. #if APR_HAVE_STDARG_H
  55. #include <stdarg.h>
  56. #endif
  57.  
  58. #ifdef __cplusplus
  59. extern "C" {
  60. #endif /* __cplusplus */
  61.  
  62. /**
  63.  * @defgroup apr_strings String routines
  64.  * @ingroup APR 
  65.  * @{
  66.  */
  67.  
  68. /**
  69.  * Do a natural order comparison of two strings.
  70.  * @param a The first string to compare
  71.  * @param b The second string to compare
  72.  * @return Either <0, 0, or >0.  If the first string is less than the second
  73.  *          this returns <0, if they are equivalent it returns 0, and if the
  74.  *          first string is greater than second string it retuns >0.
  75.  */
  76. APR_DECLARE(int) apr_strnatcmp(char const *a, char const *b);
  77.  
  78. /**
  79.  * Do a natural order comparison of two strings ignoring the case of the 
  80.  * strings.
  81.  * @param a The first string to compare
  82.  * @param b The second string to compare
  83.  * @return Either <0, 0, or >0.  If the first string is less than the second
  84.  *         this returns <0, if they are equivalent it returns 0, and if the
  85.  *         first string is greater than second string it retuns >0.
  86.  */
  87. APR_DECLARE(int) apr_strnatcasecmp(char const *a, char const *b);
  88.  
  89. /**
  90.  * duplicate a string into memory allocated out of a pool
  91.  * @param p The pool to allocate out of
  92.  * @param s The string to duplicate
  93.  * @return The new string
  94.  */
  95. APR_DECLARE(char *) apr_pstrdup(apr_pool_t *p, const char *s);
  96.  
  97. /**
  98.  * Create a null-terminated string by making a copy of a sequence
  99.  * of characters and appending a null byte
  100.  * @param p The pool to allocate out of
  101.  * @param s The block of characters to duplicate
  102.  * @param n The number of characters to duplicate
  103.  * @return The new string
  104.  * @remark This is a faster alternative to apr_pstrndup, for use
  105.  *         when you know that the string being duplicated really
  106.  *         has 'n' or more characters.  If the string might contain
  107.  *         fewer characters, use apr_pstrndup.
  108.  */
  109. APR_DECLARE(char *) apr_pstrmemdup(apr_pool_t *p, const char *s, apr_size_t n);
  110.  
  111. /**
  112.  * duplicate the first n characters of a string into memory allocated 
  113.  * out of a pool; the new string will be null-terminated
  114.  * @param p The pool to allocate out of
  115.  * @param s The string to duplicate
  116.  * @param n The number of characters to duplicate
  117.  * @return The new string
  118.  */
  119. APR_DECLARE(char *) apr_pstrndup(apr_pool_t *p, const char *s, apr_size_t n);
  120.  
  121. /**
  122.  * Duplicate a block of memory.
  123.  *
  124.  * @param p The pool to allocate from
  125.  * @param m The memory to duplicate
  126.  * @param n The number of bytes to duplicate
  127.  * @return The new block of memory
  128.  */
  129. APR_DECLARE(void *) apr_pmemdup(apr_pool_t *p, const void *m, apr_size_t n);
  130.  
  131. /**
  132.  * Concatenate multiple strings, allocating memory out a pool
  133.  * @param p The pool to allocate out of
  134.  * @param ... The strings to concatenate.  The final string must be NULL
  135.  * @return The new string
  136.  */
  137. APR_DECLARE_NONSTD(char *) apr_pstrcat(apr_pool_t *p, ...);
  138.  
  139. /**
  140.  * Concatenate multiple strings specified in a writev-style vector
  141.  * @param p The pool from which to allocate
  142.  * @param vec The strings to concatenate
  143.  * @param nvec The number of strings to concatenate
  144.  * @param nbytes (output) strlen of new string (pass in NULL to omit)
  145.  * @return The new string
  146.  */
  147. APR_DECLARE(char *) apr_pstrcatv(apr_pool_t *p, const struct iovec *vec,
  148.                                  apr_size_t nvec, apr_size_t *nbytes);
  149.  
  150. /**
  151.  * printf-style style printing routine.  The data is output to a string 
  152.  * allocated from a pool
  153.  * @param p The pool to allocate out of
  154.  * @param fmt The format of the string
  155.  * @param ap The arguments to use while printing the data
  156.  * @return The new string
  157.  */
  158. APR_DECLARE(char *) apr_pvsprintf(apr_pool_t *p, const char *fmt, va_list ap);
  159.  
  160. /**
  161.  * printf-style style printing routine.  The data is output to a string 
  162.  * allocated from a pool
  163.  * @param p The pool to allocate out of
  164.  * @param fmt The format of the string
  165.  * @param ... The arguments to use while printing the data
  166.  * @return The new string
  167.  */
  168. APR_DECLARE_NONSTD(char *) apr_psprintf(apr_pool_t *p, const char *fmt, ...)
  169.         __attribute__((format(printf,2,3)));
  170.  
  171. /**
  172.  * Copy up to dst_size characters from src to dst; does not copy
  173.  * past a NUL terminator in src, but always terminates dst with a NUL
  174.  * regardless.
  175.  * @param dst The destination string
  176.  * @param src The source string
  177.  * @param dst_size The space available in dst; dst always receives
  178.  *                 NUL termination, so if src is longer than
  179.  *                 dst_size, the actual number of characters copied is
  180.  *                 dst_size - 1.
  181.  * @return Pointer to the NUL terminator of the destination string, dst
  182.  * @remark
  183.  * <PRE>
  184.  * Note the differences between this function and strncpy():
  185.  *  1) strncpy() doesn't always NUL terminate; apr_cpystrn() does.
  186.  *  2) strncpy() pads the destination string with NULs, which is often 
  187.  *     unnecessary; apr_cpystrn() does not.
  188.  *  3) strncpy() returns a pointer to the beginning of the dst string;
  189.  *     apr_cpystrn() returns a pointer to the NUL terminator of dst, 
  190.  *     to allow a check for truncation.
  191.  * </PRE>
  192.  */
  193. APR_DECLARE(char *) apr_cpystrn(char *dst, const char *src,
  194.                                 apr_size_t dst_size);
  195.  
  196. /**
  197.  * Strip spaces from a string
  198.  * @param dest The destination string.  It is okay to modify the string
  199.  *             in place.  Namely dest == src
  200.  * @param src The string to rid the spaces from.
  201.  * @return The destination string, dest.
  202.  */
  203. APR_DECLARE(char *) apr_collapse_spaces(char *dest, const char *src);
  204.  
  205. /**
  206.  * Convert the arguments to a program from one string to an array of 
  207.  * strings terminated by a NULL pointer
  208.  * @param arg_str The arguments to convert
  209.  * @param argv_out Output location.  This is a pointer to an array of strings.
  210.  * @param token_context Pool to use.
  211.  */
  212. APR_DECLARE(apr_status_t) apr_tokenize_to_argv(const char *arg_str,
  213.                                                char ***argv_out,
  214.                                                apr_pool_t *token_context);
  215.  
  216. /**
  217.  * Split a string into separate null-terminated tokens.  The tokens are 
  218.  * delimited in the string by one or more characters from the sep
  219.  * argument.
  220.  * @param str The string to separate; this should be specified on the
  221.  *            first call to apr_strtok() for a given string, and NULL
  222.  *            on subsequent calls.
  223.  * @param sep The set of delimiters
  224.  * @param last Internal state saved by apr_strtok() between calls.
  225.  * @return The next token from the string
  226.  */
  227. APR_DECLARE(char *) apr_strtok(char *str, const char *sep, char **last);
  228.  
  229. /**
  230.  * @defgroup APR_Strings_Snprintf snprintf implementations
  231.  * @warning
  232.  * These are snprintf implementations based on apr_vformatter().
  233.  *
  234.  * Note that various standards and implementations disagree on the return
  235.  * value of snprintf, and side-effects due to %n in the formatting string.
  236.  * apr_snprintf (and apr_vsnprintf) behaves as follows:
  237.  *
  238.  * Process the format string until the entire string is exhausted, or
  239.  * the buffer fills.  If the buffer fills then stop processing immediately
  240.  * (so no further %n arguments are processed), and return the buffer
  241.  * length.  In all cases the buffer is NUL terminated. It will return the
  242.  * number of characters inserted into the buffer, not including the
  243.  * terminating NUL. As a special case, if len is 0, apr_snprintf will
  244.  * return the number of characters that would have been inserted if
  245.  * the buffer had been infinite (in this case, *buffer can be NULL)
  246.  *
  247.  * In no event does apr_snprintf return a negative number.
  248.  * @{
  249.  */
  250.  
  251. /**
  252.  * snprintf routine based on apr_vformatter.  This means it understands the
  253.  * same extensions.
  254.  * @param buf The buffer to write to
  255.  * @param len The size of the buffer
  256.  * @param format The format string
  257.  * @param ... The arguments to use to fill out the format string.
  258.  */
  259. APR_DECLARE_NONSTD(int) apr_snprintf(char *buf, apr_size_t len,
  260.                                      const char *format, ...)
  261.         __attribute__((format(printf,3,4)));
  262.  
  263. /**
  264.  * vsnprintf routine based on apr_vformatter.  This means it understands the
  265.  * same extensions.
  266.  * @param buf The buffer to write to
  267.  * @param len The size of the buffer
  268.  * @param format The format string
  269.  * @param ap The arguments to use to fill out the format string.
  270.  */
  271. APR_DECLARE(int) apr_vsnprintf(char *buf, apr_size_t len, const char *format,
  272.                                va_list ap);
  273. /** @} */
  274.  
  275. /**
  276.  * create a string representation of an int, allocated from a pool
  277.  * @param p The pool from which to allocate
  278.  * @param n The number to format
  279.  * @return The string representation of the number
  280.  */
  281. APR_DECLARE(char *) apr_itoa(apr_pool_t *p, int n);
  282.  
  283. /**
  284.  * create a string representation of a long, allocated from a pool
  285.  * @param p The pool from which to allocate
  286.  * @param n The number to format
  287.  * @return The string representation of the number
  288.  */
  289. APR_DECLARE(char *) apr_ltoa(apr_pool_t *p, long n);
  290.  
  291. /**
  292.  * create a string representation of an apr_off_t, allocated from a pool
  293.  * @param p The pool from which to allocate
  294.  * @param n The number to format
  295.  * @return The string representation of the number
  296.  */
  297. APR_DECLARE(char *) apr_off_t_toa(apr_pool_t *p, apr_off_t n);
  298.  
  299. /**
  300.  * Convert a numeric string into an apr_off_t numeric value.
  301.  * @param offset The value of the parsed string.
  302.  * @param buf The string to parse. It may contain optional whitespace,
  303.  *   followed by an optional '+' (positive, default) or '-' (negative)
  304.  *   character, followed by an optional '0x' prefix if base is 0 or 16,
  305.  *   followed by numeric digits appropriate for base.
  306.  * @param end A pointer to the end of the valid character in buf. If
  307.  *   not NULL, it is set to the first invalid character in buf.
  308.  * @param base A numeric base in the range between 2 and 36 inclusive,
  309.  *   or 0.  If base is zero, buf will be treated as base ten unless its
  310.  *   digits are prefixed with '0x', in which case it will be treated as
  311.  *   base 16.
  312.  */
  313. APR_DECLARE(apr_status_t) apr_strtoff(apr_off_t *offset, const char *buf, 
  314.                                       char **end, int base);
  315.  
  316. /**
  317.  * parse a numeric string into a 64-bit numeric value
  318.  * @param buf The string to parse. It may contain optional whitespace,
  319.  *   followed by an optional '+' (positive, default) or '-' (negative)
  320.  *   character, followed by an optional '0x' prefix if base is 0 or 16,
  321.  *   followed by numeric digits appropriate for base.
  322.  * @param end A pointer to the end of the valid character in buf. If
  323.  *   not NULL, it is set to the first invalid character in buf.
  324.  * @param base A numeric base in the range between 2 and 36 inclusive,
  325.  *   or 0.  If base is zero, buf will be treated as base ten unless its
  326.  *   digits are prefixed with '0x', in which case it will be treated as
  327.  *   base 16.
  328.  * @return The numeric value of the string.  On overflow, errno is set
  329.  * to ERANGE.
  330.  */
  331. APR_DECLARE(apr_int64_t) apr_strtoi64(const char *buf, char **end, int base);
  332.  
  333. /**
  334.  * parse a base-10 numeric string into a 64-bit numeric value.
  335.  * Equivalent to apr_strtoi64(buf, (char**)NULL, 10).
  336.  * @param buf The string to parse
  337.  * @return The numeric value of the string
  338.  */
  339. APR_DECLARE(apr_int64_t) apr_atoi64(const char *buf);
  340.  
  341. /**
  342.  * Format a binary size (magnitiudes are 2^10 rather than 10^3) from an apr_off_t,
  343.  * as bytes, K, M, T, etc, to a four character compacted human readable string.
  344.  * @param size The size to format
  345.  * @param buf The 5 byte text buffer (counting the trailing null)
  346.  * @return The buf passed to apr_strfsize()
  347.  * @remark All negative sizes report '  - ', apr_strfsize only formats positive values.
  348.  */
  349. APR_DECLARE(char *) apr_strfsize(apr_off_t size, char *buf);
  350.  
  351. /** @} */
  352.  
  353. #ifdef __cplusplus
  354. }
  355. #endif
  356.  
  357. #endif  /* !APR_STRINGS_H */
  358.